rest/meta: the /references door answers both 501 refusals in one ADR-0112 envelope - #16143

Fixes #15685

GET /api/v1/meta/:type/:name/references could refuse in two ways, and the two answers agreed on neither the envelope nor the message. Driven through the real route on one boot:

Two facts were lost on A, and both of them are the operator's.

The prescription. A's message is not decoration — findReferencesToMeta says so in as many words ("The message is prescriptive per ADR-0110 D3: it names the answerable question"). It tells the operator what to ask INSTEAD, because a field's dependents ARE reachable, through the object that owns it. That sentence is what keeps "the question was never asked" from being read as "nothing depends on it" (ADR-0110 D3, #8896) in front of an operator whose next click is a delete — this door backs the admin "Used by" panel, whose empty case renders "Nothing in the metadata graph points at this item. Safe to delete." On the wire the sentence had become "Internal server error".

The code's position. It read on B and was undefined on A — and this route's own comment on the B branch warns against exactly that dialect ("never the bare-string or sibling-code dialects, which make body.error.code read undefined"). One route was violating its own written rule at its other exit, reached by a different path.

Route taken, and the two not taken

A reached the wire through handleRouteError → declaredServerFaultAnswer, which keeps status and code and replaces the prose with INTERNAL_ERROR_MESSAGE. That arm is correct and argued for a server FAULT (#11718, #5582): a fault message may carry driver internals and withholding it is the point. What it cannot see is that a producer-declared 5xx may be a deliberate REFUSAL whose message is authored FOR the caller.

Three repairs were possible and only one is a dev's to take:

• (a) teach the relay the refusal/fault distinction — changes platform-wide behaviour for every producer-declared 5xx at every door. Maintainer's call.
• (b) this route catches its protocol's refusal and re-answers it in the nested envelope its sibling exit already publishes — bounded to one door. Taken.
• (c) move the refusal off 5xx entirely — a published route changing status band. Maintainer's call.

(b) is also what the producer already believed was happening: findReferencesToMeta's own comment says its refusal "reuses the ADR-0112 nested envelope and the SAME 501 NOT_IMPLEMENTED code the sibling refusal on this exact route already returns. One route, one dialect for 'the question was never asked'." The relay was silently making that false. This restores the door to its written contract rather than inventing one.

(b)'s known incompleteness is written down rather than left implied, and is handed back as its own finding: declaredServerFaultAnswer still cannot distinguish a deliberate refusal from a server fault, so every OTHER producer-declared 5xx refusal in the repo still loses its prose at every door.

How narrow the arm is

notImplementedRefusalAnswer (module-scope in rest-server.ts) fires only on a producer-declared 501 carrying this route's own published refusal code and a non-empty message, and the catch is scoped to the findReferencesToMeta call ALONE — so what it can re-dress is mechanically the set of things the protocol raised; neither resolveProtocol nor the resolveExecCtx seam above it can reach the arm, whatever they declare.

Matching the literal code rather than "any declared code" is also how the #9232 vocabulary narrowing is honoured by CONSTRUCTION: an unregistered producer spelling can never reach this exit, so no second copy of thrownCodeFields' demotion rule is needed and no new door ships an un-narrowed code. The cost is stated in the docblock rather than hidden: a future SECOND refusal code on this route falls back to the flat fault answer until whoever adds it comes here.

The producer's message is relayed VERBATIM, [unanswerable_target] prefix included. Editing it would be a third local opinion at a boundary whose module argues against exactly that; the prefix is the producer's own prose and is filed as a separate observation.

declaredHttpStatus is exported from error-response.ts so the arm asks the existing two-spelling question (status / statusCode, #7525) instead of re-deriving it. A read, no wire byte moves, and error-response.ts is not part of @objectstack/rest's package entry, so nothing published changes.

Measurement

⚠️ The card's repro command is NOT the criterion. rest-server-meta-read-org-scope.test.ts -t 'unanswerable-target' reads the code through both dialects on purpose, so it is green under both shapes — before and after. Reproduced: under the ablation below it stays GREEN while the new pin goes red.

New pin: packages/rest/src/rest-server-meta-references-refusal-envelope.test.ts — 7 tests, both refusals driven on the real route table, assertions POSITIONAL because position is half the finding. It pins the prescription reaching the caller, body.error.code reading the same way on both refusals in ONE comparison, and the arm's boundaries: a producer-declared 503 keeps its withheld generic message and its flat body (driver internals asserted absent), and a 501 declaring a code this door does not publish stays on the fault terminal. Anti-vacuity: an answerable target on the same harness still answers 200 {"references":[]}, and INTERNAL_ERROR_MESSAGE is pinned to the exact text A used to ship.

Ablation, direction predicted in writing before the run: delete the route's re-dress arm, restoring the pre-fix const result = await …; res.json(result);. Predicted RED on exactly two of the seven — the prescription test and the code-position test — with the other five green and the org-scope file untouched.

Observed, exactly that:

× names the answerable question instead of "Internal server error"
× both are the ADR-0112 NESTED envelope, with the code in ONE place
  AssertionError: expected [ undefined, 'NOT_IMPLEMENTED' ] to deeply equal [ Array(2) ]
Test Files  1 failed | 1 passed (2)
Tests  2 failed | 46 passed (48)

The mutation was confirmed on disk before the run (arm call sites 1 → 0, pre-fix spelling restored 0 → 1, blob hash differs from the HEAD blob) and the restore was proved after it (git diff HEAD empty, restored blob byte-identical to the HEAD blob). No build leg: packages/rest/dist does not exist in this worktree and the pins import ./rest-server.js relatively, so vitest resolves source.

Suite: pnpm --filter @objectstack/rest exec vitest run — 186 files, 3168 tests, green. pnpm --filter @objectstack/rest run typecheck green, and its check:test-typecheck half compiles the test layer under tsconfig.test.json; all three touched test files were confirmed present in that program with tsc --listFiles, so the coverage claim is measured rather than assumed.

Gates, harvested on this PR's head c747061cfcc, exit codes captured BEFORE any pipe. node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derives 55 commands on the code-only diff and 92 once the doc anchor repair joins it, asserted against its own Reconciliation — 92 famil(ies) line. 90 of 92 exit 0. The two that do not are NOT MEASURED, not passes: check:dual-build-cjs-loads and check:type-check-debt both exit 3 with PREREQUISITE NOT MET — each reads built output for every package and asks for a whole-repo pnpm build, which does not fit a foreground turn on a shared box. CI runs both after its own build. The 36 Artifact rosters were run separately and are not part of that 92: 32 green; check-partof-closing-keyword.mjs and check-single-claim-paths.mjs exit 2 = NOT WIRED (no PR_BODY / PR_NUMBER outside CI — and their pnpm spellings resolve to --self-test only, which grades the checker's fixtures, not this diff, per #16030); check:react-declaration-parity prints "MANIFEST is not set … This gate did NOT run"; check:published-readme-exports exits 3, same whole-build prerequisite.

Three gate-owned follow-ons, each its own commit and none a behaviour change: the new fixture's findOne opens with assertEngineFindOnePredicate and the RETAINED ledger records the pin; ten anchors in content/docs/permissions/system-context.mdx were re-anchored by check-system-context-census.mjs --fix after the arm and its helper moved every elevation read site below them (+88 above the route, +109 below it), pure line rot with no row added, removed or re-worded; and the execCtx census records 77 → 77 sites / 99 → 100 mentions — one prose mention, no call site, which is that two-number control working.

Changeset

patch on @objectstack/rest — a bug fix in a released package. Not breaking: nothing an author can write is removed or renamed, no exported surface is withdrawn, and @objectstack/client already reads the code from either position (errorBody?.code ?? errorBody?.error?.code), so err.code is unchanged for SDK callers while err.message improves from Internal server error to the prescriptive sentence. No **BREAKING** banner and therefore no ADR-0087 disposition marker; check:adr-0087-registration and check:changeset-no-major are both green above. The changeset body states the position change for raw HTTP callers.

Not folded in, deliberately

#15620 (the falsified getMetaItems comment on this same door) and #15622 (the unspecified-type sweep's organization forwarding, a decision box) are separate cards on the same door and stay separate. #13753 is the organization-forwarding half and moves no status code, field or message; the one place this PR touches its pin is the #9327 refusal read, whose comment described the divergence as standing and is rewritten rather than left falsified.

⚠️ For whoever squashes: the authoritative card relation is the single Fixes #15685 above. The per-commit trailers were written before that convention was applied on this branch and the follow-on commits carry Part of #15685; rewriting them would need an amend or a force-push, both of which are off-limits here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01D47qPfEWVPmhguWgBZCi5N

Generated by Claude Code